home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 2002 November / SGI Freeware 2002 November - Disc 1.iso / dist / fw_apache2.idb / usr / freeware / apache2 / include / apr_thread_proc.h.z / apr_thread_proc.h
C/C++ Source or Header  |  2002-07-08  |  28KB  |  688 lines
  1. /* ====================================================================
  2.  * The Apache Software License, Version 1.1
  3.  *
  4.  * Copyright (c) 2000-2002 The Apache Software Foundation.  All rights
  5.  * reserved.
  6.  *
  7.  * Redistribution and use in source and binary forms, with or without
  8.  * modification, are permitted provided that the following conditions
  9.  * are met:
  10.  *
  11.  * 1. Redistributions of source code must retain the above copyright
  12.  *    notice, this list of conditions and the following disclaimer.
  13.  *
  14.  * 2. Redistributions in binary form must reproduce the above copyright
  15.  *    notice, this list of conditions and the following disclaimer in
  16.  *    the documentation and/or other materials provided with the
  17.  *    distribution.
  18.  *
  19.  * 3. The end-user documentation included with the redistribution,
  20.  *    if any, must include the following acknowledgment:
  21.  *       "This product includes software developed by the
  22.  *        Apache Software Foundation (http://www.apache.org/)."
  23.  *    Alternately, this acknowledgment may appear in the software itself,
  24.  *    if and wherever such third-party acknowledgments normally appear.
  25.  *
  26.  * 4. The names "Apache" and "Apache Software Foundation" must
  27.  *    not be used to endorse or promote products derived from this
  28.  *    software without prior written permission. For written
  29.  *    permission, please contact apache@apache.org.
  30.  *
  31.  * 5. Products derived from this software may not be called "Apache",
  32.  *    nor may "Apache" appear in their name, without prior written
  33.  *    permission of the Apache Software Foundation.
  34.  *
  35.  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  36.  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  37.  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  38.  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  39.  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  40.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  41.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  42.  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  43.  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  44.  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  45.  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  46.  * SUCH DAMAGE.
  47.  * ====================================================================
  48.  *
  49.  * This software consists of voluntary contributions made by many
  50.  * individuals on behalf of the Apache Software Foundation.  For more
  51.  * information on the Apache Software Foundation, please see
  52.  * <http://www.apache.org/>.
  53.  */
  54.  
  55. #ifndef APR_THREAD_PROC_H
  56. #define APR_THREAD_PROC_H
  57.  
  58. #include "apr.h"
  59. #include "apr_file_io.h"
  60. #include "apr_pools.h"
  61. #include "apr_errno.h"
  62.  
  63. #if APR_HAVE_STRUCT_RLIMIT
  64. #include <sys/time.h>
  65. #include <sys/resource.h>
  66. #endif
  67.  
  68.  
  69. #ifdef __cplusplus
  70. extern "C" {
  71. #endif /* __cplusplus */
  72. /**
  73.  * @file apr_thread_proc.h
  74.  * @brief APR Thread and Process Library
  75.  */
  76. /**
  77.  * @defgroup APR_Thread Thread Library
  78.  * @ingroup APR
  79.  * @{
  80.  */
  81.  
  82. typedef enum {
  83.     APR_SHELLCMD,       /**< use the shell to invoke the program */
  84.     APR_PROGRAM,        /**< invoke the program directly, no copied env */
  85.     APR_PROGRAM_ENV,    /**< invoke the program, replicating our environment */
  86.     APR_PROGRAM_PATH    /**< find program on PATH, use our environment */
  87. } apr_cmdtype_e;
  88.  
  89. typedef enum {
  90.     APR_WAIT,           /**< wait for the specified process to finish */
  91.     APR_NOWAIT          /**< do not wait -- just see if it has finished */
  92. } apr_wait_how_e;
  93.  
  94. /* I am specifically calling out the values so that the macros below make
  95.  * more sense.  Yes, I know I don't need to, but I am hoping this makes what
  96.  * I am doing more clear.  If you want to add more reasons to exit, continue
  97.  * to use bitmasks.
  98.  */
  99. typedef enum {
  100.     APR_PROC_EXIT = 1,          /**< process exited normally */
  101.     APR_PROC_SIGNAL = 2,        /**< process exited due to a signal */
  102.     APR_PROC_SIGNAL_CORE = 4    /**< process exited and dumped a core file */
  103. } apr_exit_why_e;
  104.  
  105. /** did we exit the process */
  106. #define APR_PROC_CHECK_EXIT(x)        (x & APR_PROC_EXIT)
  107. /** did we get a signal */
  108. #define APR_PROC_CHECK_SIGNALED(x)    (x & APR_PROC_SIGNAL)
  109. /** did we get core */
  110. #define APR_PROC_CHECK_CORE_DUMP(x)   (x & APR_PROC_SIGNAL_CORE)
  111.  
  112. /** @see apr_procattr_io_set */
  113. #define APR_NO_PIPE          0
  114.  
  115. /** @see apr_procattr_io_set */
  116. #define APR_FULL_BLOCK       1
  117. /** @see apr_procattr_io_set */
  118. #define APR_FULL_NONBLOCK    2
  119. /** @see apr_procattr_io_set */
  120. #define APR_PARENT_BLOCK     3
  121. /** @see apr_procattr_io_set */
  122. #define APR_CHILD_BLOCK      4
  123.  
  124. /** @see apr_procattr_limit_set */
  125. #define APR_LIMIT_CPU        0
  126. /** @see apr_procattr_limit_set */
  127. #define APR_LIMIT_MEM        1
  128. /** @see apr_procattr_limit_set */
  129. #define APR_LIMIT_NPROC      2
  130.  
  131. #if APR_HAS_OTHER_CHILD || defined(DOXYGEN)
  132. /**
  133.  * @defgroup Other_Child Other Child Flags
  134.  * @{
  135.  */
  136. #define APR_OC_REASON_DEATH         0     /**< child has died, caller must call
  137.                                            * unregister still */
  138. #define APR_OC_REASON_UNWRITABLE    1     /**< write_fd is unwritable */
  139. #define APR_OC_REASON_RESTART       2     /**< a restart is occuring, perform
  140.                                            * any necessary cleanup (including
  141.                                            * sending a special signal to child)
  142.                                            */
  143. #define APR_OC_REASON_UNREGISTER    3     /**< unregister has been called, do
  144.                                            * whatever is necessary (including
  145.                                            * kill the child) */
  146. #define APR_OC_REASON_LOST          4     /**< somehow the child exited without
  147.                                            * us knowing ... buggy os? */
  148. /** @} */
  149. #endif /* APR_HAS_OTHER_CHILD */
  150.  
  151. typedef struct apr_proc_t apr_proc_t;
  152.  
  153. /** The APR process type */
  154. struct apr_proc_t {
  155.     /** The process ID */
  156.     pid_t pid;
  157.     /** Parent's side of pipe to child's stdin */
  158.     apr_file_t *in;
  159.     /** Parent's side of pipe to child's stdout */
  160.     apr_file_t *out;
  161.     /** Parent's side of pipe to child's stdouterr */
  162.     apr_file_t *err;
  163. #if APR_HAS_PROC_INVOKED || defined(DOXYGEN)
  164.     /** Diagnositics/debugging string of the command invoked for 
  165.      *  this process [only present if APR_HAS_PROC_INVOKED is true]
  166.      */
  167.     char *invoked;
  168. #endif
  169. #if defined(WIN32) || defined(DOXYGEN)
  170.     /** Win32 specific: Must retain the creator's handle granting 
  171.      *  access, as a new copy may not grant the same permissions 
  172.      */
  173.     HANDLE hproc;
  174. #endif
  175. };
  176.  
  177. typedef struct apr_thread_t           apr_thread_t;
  178. typedef struct apr_threadattr_t       apr_threadattr_t;
  179. typedef struct apr_procattr_t         apr_procattr_t;
  180. typedef struct apr_thread_once_t      apr_thread_once_t;
  181.  
  182. typedef struct apr_threadkey_t        apr_threadkey_t;
  183. #if APR_HAS_OTHER_CHILD
  184. typedef struct apr_other_child_rec_t  apr_other_child_rec_t;
  185. #endif /* APR_HAS_OTHER_CHILD */
  186.  
  187. /**
  188.  * The prototype for any APR thread worker functions.
  189.  */
  190. typedef void *(APR_THREAD_FUNC *apr_thread_start_t)(apr_thread_t*, void*);
  191.  
  192. typedef enum {
  193.     APR_KILL_NEVER,             /**< process is never sent any signals */
  194.     APR_KILL_ALWAYS,            /**< process is sent SIGKILL on apr_pool_t cleanup */
  195.     APR_KILL_AFTER_TIMEOUT,     /**< SIGTERM, wait 3 seconds, SIGKILL */
  196.     APR_JUST_WAIT,              /**< wait forever for the process to complete */
  197.     APR_KILL_ONLY_ONCE          /**< send SIGTERM and then wait */
  198. } apr_kill_conditions_e;
  199.  
  200. /* Thread Function definitions */
  201.  
  202. #if APR_HAS_THREADS
  203.  
  204. /**
  205.  * Create and initialize a new threadattr variable
  206.  * @param new_attr The newly created threadattr.
  207.  * @param cont The pool to use
  208.  */
  209. APR_DECLARE(apr_status_t) apr_threadattr_create(apr_threadattr_t **new_attr, 
  210.                                                 apr_pool_t *cont);
  211.  
  212. /**
  213.  * Set if newly created threads should be created in detached state.
  214.  * @param attr The threadattr to affect 
  215.  * @param on Thread detach state on or off
  216.  */
  217. APR_DECLARE(apr_status_t) apr_threadattr_detach_set(apr_threadattr_t *attr, 
  218.                                                    apr_int32_t on);
  219.  
  220. /**
  221.  * Get the detach state for this threadattr.
  222.  * @param attr The threadattr to reference 
  223.  */
  224. APR_DECLARE(apr_status_t) apr_threadattr_detach_get(apr_threadattr_t *attr);
  225.  
  226. /**
  227.  * Create a new thread of execution
  228.  * @param new_thread The newly created thread handle.
  229.  * @param attr The threadattr to use to determine how to create the thread
  230.  * @param func The function to start the new thread in
  231.  * @param data Any data to be passed to the starting function
  232.  * @param cont The pool to use
  233.  */
  234. APR_DECLARE(apr_status_t) apr_thread_create(apr_thread_t **new_thread, 
  235.                                             apr_threadattr_t *attr, 
  236.                                             apr_thread_start_t func, 
  237.                                             void *data, apr_pool_t *cont);
  238.  
  239. /**
  240.  * stop the current thread
  241.  * @param thd The thread to stop
  242.  * @param retval The return value to pass back to any thread that cares
  243.  */
  244. APR_DECLARE(apr_status_t) apr_thread_exit(apr_thread_t *thd, 
  245.                                           apr_status_t retval);
  246.  
  247. /**
  248.  * block until the desired thread stops executing.
  249.  * @param retval The return value from the dead thread.
  250.  * @param thd The thread to join
  251.  */
  252. APR_DECLARE(apr_status_t) apr_thread_join(apr_status_t *retval, 
  253.                                           apr_thread_t *thd); 
  254.  
  255. /**
  256.  * force the current thread to yield the processor
  257.  */
  258. APR_DECLARE(void) apr_thread_yield(void);
  259.  
  260. /**
  261.  * Initialize the control variable for apr_thread_once.  If this isn't
  262.  * called, apr_initialize won't work.
  263.  * @param control The control variable to initialize
  264.  * @param p The pool to allocate data from.
  265.  */
  266. APR_DECLARE(apr_status_t) apr_thread_once_init(apr_thread_once_t **control,
  267.                                                apr_pool_t *p);
  268.  
  269. /**
  270.  * Run the specified function one time, regardless of how many threads
  271.  * call it.
  272.  * @param control The control variable.  The same variable should
  273.  *                be passed in each time the function is tried to be
  274.  *                called.  This is how the underlying functions determine
  275.  *                if the function has ever been called before.
  276.  * @param func The function to call.
  277.  */
  278. APR_DECLARE(apr_status_t) apr_thread_once(apr_thread_once_t *control,
  279.                                           void (*func)(void));
  280.  
  281. /**
  282.  * detach a thread
  283.  * @param thd The thread to detach 
  284.  */
  285. APR_DECLARE(apr_status_t) apr_thread_detach(apr_thread_t *thd);
  286.  
  287. /**
  288.  * Return the pool associated with the current thread.
  289.  * @param data The user data associated with the thread.
  290.  * @param key The key to associate with the data
  291.  * @param thread The currently open thread.
  292.  */
  293. APR_DECLARE(apr_status_t) apr_thread_data_get(void **data, const char *key,
  294.                                              apr_thread_t *thread);
  295.  
  296. /**
  297.  * Return the pool associated with the current thread.
  298.  * @param data The user data to associate with the thread.
  299.  * @param key The key to use for associating the data with the tread
  300.  * @param cleanup The cleanup routine to use when the thread is destroyed.
  301.  * @param thread The currently open thread.
  302.  */
  303. APR_DECLARE(apr_status_t) apr_thread_data_set(void *data, const char *key,
  304.                                              apr_status_t (*cleanup) (void *),
  305.                                              apr_thread_t *thread);
  306.  
  307. /**
  308.  * Create and initialize a new thread private address space
  309.  * @param key The thread private handle.
  310.  * @param dest The destructor to use when freeing the private memory.
  311.  * @param cont The pool to use
  312.  */
  313. APR_DECLARE(apr_status_t) apr_threadkey_private_create(apr_threadkey_t **key, 
  314.                                                     void (*dest)(void *),
  315.                                                     apr_pool_t *cont);
  316.  
  317. /**
  318.  * Get a pointer to the thread private memory
  319.  * @param new_mem The data stored in private memory 
  320.  * @param key The handle for the desired thread private memory 
  321.  */
  322. APR_DECLARE(apr_status_t) apr_threadkey_private_get(void **new_mem, 
  323.                                                  apr_threadkey_t *key);
  324.  
  325. /**
  326.  * Set the data to be stored in thread private memory
  327.  * @param priv The data to be stored in private memory 
  328.  * @param key The handle for the desired thread private memory 
  329.  */
  330. APR_DECLARE(apr_status_t) apr_threadkey_private_set(void *priv, 
  331.                                                  apr_threadkey_t *key);
  332.  
  333. /**
  334.  * Free the thread private memory
  335.  * @param key The handle for the desired thread private memory 
  336.  */
  337. APR_DECLARE(apr_status_t) apr_threadkey_private_delete(apr_threadkey_t *key);
  338.  
  339. /**
  340.  * Return the pool associated with the current threadkey.
  341.  * @param data The user data associated with the threadkey.
  342.  * @param key The key associated with the data
  343.  * @param threadkey The currently open threadkey.
  344.  */
  345. APR_DECLARE(apr_status_t) apr_threadkey_data_get(void **data, const char *key,
  346.                                                 apr_threadkey_t *threadkey);
  347.  
  348. /**
  349.  * Return the pool associated with the current threadkey.
  350.  * @param data The data to set.
  351.  * @param key The key to associate with the data.
  352.  * @param cleanup The cleanup routine to use when the file is destroyed.
  353.  * @param threadkey The currently open threadkey.
  354.  */
  355. APR_DECLARE(apr_status_t) apr_threadkey_data_set(void *data, const char *key,
  356.                                                 apr_status_t (*cleanup) (void *),
  357.                                                 apr_threadkey_t *threadkey);
  358.  
  359. #endif
  360.  
  361. /* Process Function definitions */
  362.  
  363. /**
  364.  * @package APR Process library
  365.  */
  366.  
  367. /**
  368.  * Create and initialize a new procattr variable
  369.  * @param new_attr The newly created procattr. 
  370.  * @param cont The pool to use
  371.  */
  372. APR_DECLARE(apr_status_t) apr_procattr_create(apr_procattr_t **new_attr,
  373.                                                   apr_pool_t *cont);
  374.  
  375. /**
  376.  * Determine if any of stdin, stdout, or stderr should be linked to pipes 
  377.  * when starting a child process.
  378.  * @param attr The procattr we care about. 
  379.  * @param in Should stdin be a pipe back to the parent?
  380.  * @param out Should stdout be a pipe back to the parent?
  381.  * @param err Should stderr be a pipe back to the parent?
  382.  */
  383. APR_DECLARE(apr_status_t) apr_procattr_io_set(apr_procattr_t *attr, 
  384.                                              apr_int32_t in, apr_int32_t out,
  385.                                              apr_int32_t err);
  386.  
  387. /**
  388.  * Set the child_in and/or parent_in values to existing apr_file_t values.
  389.  * @param attr The procattr we care about. 
  390.  * @param child_in apr_file_t value to use as child_in. Must be a valid file.
  391.  * @param parent_in apr_file_t value to use as parent_in. Must be a valid file.
  392.  * @remark  This is NOT a required initializer function. This is
  393.  *          useful if you have already opened a pipe (or multiple files)
  394.  *          that you wish to use, perhaps persistently across multiple
  395.  *          process invocations - such as a log file. You can save some 
  396.  *          extra function calls by not creating your own pipe since this
  397.  *          creates one in the process space for you.
  398.  */
  399. APR_DECLARE(apr_status_t) apr_procattr_child_in_set(struct apr_procattr_t *attr,
  400.                                                   apr_file_t *child_in,
  401.                                                   apr_file_t *parent_in);
  402.  
  403. /**
  404.  * Set the child_out and parent_out values to existing apr_file_t values.
  405.  * @param attr The procattr we care about. 
  406.  * @param child_out apr_file_t value to use as child_out. Must be a valid file.
  407.  * @param parent_out apr_file_t value to use as parent_out. Must be a valid file.
  408.  * @remark This is NOT a required initializer function. This is
  409.  *         useful if you have already opened a pipe (or multiple files)
  410.  *         that you wish to use, perhaps persistently across multiple
  411.  *         process invocations - such as a log file. 
  412.  */
  413. APR_DECLARE(apr_status_t) apr_procattr_child_out_set(struct apr_procattr_t *attr,
  414.                                                    apr_file_t *child_out,
  415.                                                    apr_file_t *parent_out);
  416.  
  417. /**
  418.  * Set the child_err and parent_err values to existing apr_file_t values.
  419.  * @param attr The procattr we care about. 
  420.  * @param child_err apr_file_t value to use as child_err. Must be a valid file.
  421.  * @param parent_err apr_file_t value to use as parent_err. Must be a valid file.
  422.  * @remark This is NOT a required initializer function. This is
  423.  *         useful if you have already opened a pipe (or multiple files)
  424.  *         that you wish to use, perhaps persistently across multiple
  425.  *         process invocations - such as a log file. 
  426.  */
  427. APR_DECLARE(apr_status_t) apr_procattr_child_err_set(struct apr_procattr_t *attr,
  428.                                                    apr_file_t *child_err,
  429.                                                    apr_file_t *parent_err);
  430.  
  431. /**
  432.  * Set which directory the child process should start executing in.
  433.  * @param attr The procattr we care about. 
  434.  * @param dir Which dir to start in.  By default, this is the same dir as
  435.  *            the parent currently resides in, when the createprocess call
  436.  *            is made. 
  437.  */
  438. APR_DECLARE(apr_status_t) apr_procattr_dir_set(apr_procattr_t *attr, 
  439.                                               const char *dir);
  440.  
  441. /**
  442.  * Set what type of command the child process will call.
  443.  * @param attr The procattr we care about. 
  444.  * @param cmd The type of command.  One of:
  445.  * <PRE>
  446.  *            APR_SHELLCMD     --  Shell script
  447.  *            APR_PROGRAM      --  Executable program   (default) 
  448.  *            APR_PROGRAM_ENV  --  Executable program, copy environment
  449.  *            APR_PROGRAM_PATH --  Executable program on PATH, copy env
  450.  * </PRE>
  451.  */
  452. APR_DECLARE(apr_status_t) apr_procattr_cmdtype_set(apr_procattr_t *attr,
  453.                                                   apr_cmdtype_e cmd);
  454.  
  455. /**
  456.  * Determine if the chlid should start in detached state.
  457.  * @param attr The procattr we care about. 
  458.  * @param detach Should the child start in detached state?  Default is no. 
  459.  */
  460. APR_DECLARE(apr_status_t) apr_procattr_detach_set(apr_procattr_t *attr, 
  461.                                                  apr_int32_t detach);
  462.  
  463. #if APR_HAVE_STRUCT_RLIMIT
  464. /**
  465.  * Set the Resource Utilization limits when starting a new process.
  466.  * @param attr The procattr we care about. 
  467.  * @param what Which limit to set, one of:
  468.  * <PRE>
  469.  *                 APR_LIMIT_CPU
  470.  *                 APR_LIMIT_MEM
  471.  *                 APR_LIMIT_NPROC
  472.  * </PRE>
  473.  * @param limit Value to set the limit to.
  474.  */
  475. APR_DECLARE(apr_status_t) apr_procattr_limit_set(apr_procattr_t *attr, 
  476.                                                 apr_int32_t what,
  477.                                                 struct rlimit *limit);
  478. #endif
  479.  
  480. #if APR_HAS_FORK
  481. /**
  482.  * This is currently the only non-portable call in APR.  This executes 
  483.  * a standard unix fork.
  484.  * @param proc The resulting process handle. 
  485.  * @param cont The pool to use. 
  486.  */
  487. APR_DECLARE(apr_status_t) apr_proc_fork(apr_proc_t *proc, apr_pool_t *cont);
  488. #endif
  489.  
  490. /**
  491.  * Create a new process and execute a new program within that process.
  492.  * @param new_proc The resulting process handle.
  493.  * @param progname The program to run 
  494.  * @param const_args the arguments to pass to the new program.  The first 
  495.  *                   one should be the program name.
  496.  * @param env The new environment table for the new process.  This 
  497.  *            should be a list of NULL-terminated strings. This argument
  498.  *            is ignored for APR_PROGRAM_ENV and APR_PROGRAM_PATH types
  499.  *            of commands.
  500.  * @param attr the procattr we should use to determine how to create the new
  501.  *         process
  502.  * @param cont The pool to use. 
  503.  */
  504. APR_DECLARE(apr_status_t) apr_proc_create(apr_proc_t *new_proc,
  505.                                              const char *progname,
  506.                                              const char * const *args,
  507.                                              const char * const *env, 
  508.                                              apr_procattr_t *attr, 
  509.                                              apr_pool_t *cont);
  510.  
  511. /**
  512.  * Wait for a child process to die
  513.  * @param proc The process handle that corresponds to the desired child process 
  514.  * @param exitcode The returned exit status of the child, if a child process 
  515.  *                 dies, or the signal that caused the child to die.
  516.  *                 On platforms that don't support obtaining this information, 
  517.  *                 the status parameter will be returned as APR_ENOTIMPL.
  518.  * @param exitwhy Why the child died, the bitwise or of:
  519.  * <PRE>
  520.  *            APR_PROC_EXIT         -- process terminated normally
  521.  *            APR_PROC_SIGNAL       -- process was killed by a signal
  522.  *            APR_PROC_SIGNAL_CORE  -- process was killed by a signal, and
  523.  *                                     generated a core dump.
  524.  * </PRE>
  525.  * @param waithow How should we wait.  One of:
  526.  * <PRE>
  527.  *            APR_WAIT   -- block until the child process dies.
  528.  *            APR_NOWAIT -- return immediately regardless of if the 
  529.  *                          child is dead or not.
  530.  * </PRE>
  531.  * @remark The childs status is in the return code to this process.  It is one of:
  532.  * <PRE>
  533.  *            APR_CHILD_DONE     -- child is no longer running.
  534.  *            APR_CHILD_NOTDONE  -- child is still running.
  535.  * </PRE>
  536.  */
  537. APR_DECLARE(apr_status_t) apr_proc_wait(apr_proc_t *proc,
  538.                                         int *exitcode, apr_exit_why_e *exitwhy,
  539.                                         apr_wait_how_e waithow);
  540.  
  541. /**
  542.  * Wait for any current child process to die and return information 
  543.  * about that child.
  544.  * @param proc Pointer to NULL on entry, will be filled out with child's 
  545.  *             information 
  546.  * @param exitcode The returned exit status of the child, if a child process 
  547.  *                 dies, or the signal that caused the child to die.
  548.  *                 On platforms that don't support obtaining this information, 
  549.  *                 the status parameter will be returned as APR_ENOTIMPL.
  550.  * @param exitwhy Why the child died, the bitwise or of:
  551.  * <PRE>
  552.  *            APR_PROC_EXIT         -- process terminated normally
  553.  *            APR_PROC_SIGNAL       -- process was killed by a signal
  554.  *            APR_PROC_SIGNAL_CORE  -- process was killed by a signal, and
  555.  *                                     generated a core dump.
  556.  * </PRE>
  557.  * @param waithow How should we wait.  One of:
  558.  * <PRE>
  559.  *            APR_WAIT   -- block until the child process dies.
  560.  *            APR_NOWAIT -- return immediately regardless of if the 
  561.  *                          child is dead or not.
  562.  * </PRE>
  563.  * @param p Pool to allocate child information out of.
  564.  */
  565. APR_DECLARE(apr_status_t) apr_proc_wait_all_procs(apr_proc_t *proc,
  566.                                                   int *exitcode,
  567.                                                   apr_exit_why_e *exitwhy,
  568.                                                   apr_wait_how_e waithow,
  569.                                                   apr_pool_t *p);
  570.  
  571. #define APR_PROC_DETACH_FOREGROUND 0
  572. #define APR_PROC_DETACH_DAEMONIZE 1
  573.  
  574. /**
  575.  * Detach the process from the controlling terminal.
  576.  * @param daemonize set to non-zero if the process should daemonize
  577.  *                  and become a background process, else it will
  578.  *                  stay in the foreground.
  579.  */
  580. APR_DECLARE(apr_status_t) apr_proc_detach(int daemonize);
  581.  
  582. #if APR_HAS_OTHER_CHILD
  583.  
  584. /**
  585.  * Register an other_child -- a child which must be kept track of so 
  586.  * that the program knows when it has died or disappeared.
  587.  * @param pid pid is the pid of the child.
  588.  * @param maintenance maintenance is a function that is invoked with a 
  589.  *                    reason and the data pointer passed here.
  590.  * @param data The data to pass to the maintenance function.
  591.  * @param write_fd An fd that is probed for writing.  If it is ever unwritable
  592.  *                 then the maintenance is invoked with reason 
  593.  *                 OC_REASON_UNWRITABLE.
  594.  * @param p The pool to use for allocating memory.
  595.  */
  596. APR_DECLARE(void) apr_proc_other_child_register(apr_proc_t *pid, 
  597.                                            void (*maintenance) (int reason, 
  598.                                                                 void *, 
  599.                                                                 int status),
  600.                                            void *data, apr_file_t *write_fd,
  601.                                            apr_pool_t *p);
  602.  
  603. /**
  604.  * Stop watching the specified process.
  605.  * @param data The data to pass to the maintenance function.  This is
  606.  *             used to find the process to unregister.
  607.  * @warning Since this can be called by a maintenance function while we're
  608.  *          scanning the other_children list, all scanners should protect 
  609.  *          themself by loading ocr->next before calling any maintenance 
  610.  *          function.
  611.  */
  612. APR_DECLARE(void) apr_proc_other_child_unregister(void *data);
  613.  
  614. /**
  615.  * Check on the specified process.  If it is gone, call the maintenance 
  616.  * function.
  617.  * @param pid The process to check.
  618.  * @param status The status to pass to the maintenance function.
  619.  */
  620. APR_DECLARE(apr_status_t) apr_proc_other_child_read(apr_proc_t *pid, int status);
  621.  
  622. /**
  623.  * Loop through all registered other_children and call the appropriate 
  624.  * maintenance function when necessary.
  625.  */
  626. APR_DECLARE(void) apr_proc_other_child_check(void); 
  627.  
  628. #endif /* APR_HAS_OTHER_CHILD */
  629.  
  630. /** 
  631.  * Terminate a process.
  632.  * @param proc The process to terminate.
  633.  * @param sig How to kill the process.
  634.  */
  635. APR_DECLARE(apr_status_t) apr_proc_kill(apr_proc_t *proc, int sig);
  636.  
  637. /**
  638.  * Register a process to be killed when a pool dies.
  639.  * @param a The pool to use to define the processes lifetime 
  640.  * @param pid The process to register
  641.  * @param how How to kill the process, one of:
  642.  * <PRE>
  643.  *         APR_KILL_NEVER         -- process is never sent any signals
  644.  *         APR_KILL_ALWAYS        -- process is sent SIGKILL on apr_pool_t cleanup
  645.  *         APR_KILL_AFTER_TIMEOUT -- SIGTERM, wait 3 seconds, SIGKILL
  646.  *         APR_JUST_WAIT          -- wait forever for the process to complete
  647.  *         APR_KILL_ONLY_ONCE     -- send SIGTERM and then wait
  648.  * </PRE>
  649.  */
  650. APR_DECLARE(void) apr_pool_note_subprocess(apr_pool_t *a, apr_proc_t *pid,
  651.                                            apr_kill_conditions_e how);
  652.  
  653. #if APR_HAS_THREADS 
  654.  
  655. #if (APR_HAVE_SIGWAIT || APR_HAVE_SIGSUSPEND) && !defined(OS2)
  656.  
  657. /**
  658.  * Setup the process for a single thread to be used for all signal handling.
  659.  * @warning This must be called before any threads are created
  660.  */
  661. APR_DECLARE(apr_status_t) apr_setup_signal_thread(void);
  662.  
  663. /**
  664.  * Make the current thread listen for signals.  This thread will loop
  665.  * forever, calling a provided function whenever it receives a signal.  That
  666.  * functions should return 1 if the signal has been handled, 0 otherwise.
  667.  * @param signal_handler The function to call when a signal is received
  668.  * apr_status_t apr_signal_thread((int)(*signal_handler)(int signum))
  669.  */
  670. APR_DECLARE(apr_status_t) apr_signal_thread(int(*signal_handler)(int signum));
  671.  
  672. #endif /* (APR_HAVE_SIGWAIT || APR_HAVE_SIGSUSPEND) && !defined(OS2) */
  673.  
  674. /**
  675.  * Get the child-pool used by the thread from the thread info.
  676.  * @return apr_pool_t the pool
  677.  */
  678. APR_POOL_DECLARE_ACCESSOR(thread);
  679.  
  680. #endif /* APR_HAS_THREADS */
  681. /** @} */
  682. #ifdef __cplusplus
  683. }
  684. #endif
  685.  
  686. #endif  /* ! APR_THREAD_PROC_H */
  687.  
  688.